package zzuli.edu.cn.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

// https://blog.csdn.net/ajklaclk/article/details/80736042
// https://www.jianshu.com/p/925d1c732d15
/**
 * @Api 注解的作用:用于表示标识这个类是swagger的资源
 * value: 类的描述(对内，不会在页面展示)
 * tags: 类的描述(对外，会在页面展示)，它是一个String数组，如果tags如果有多个值，那么就会在页面生成多个API描述
 */
@Api(value = "@Api注解测试", tags = {"@Api注解测试1", "@Api注解测试2"})
@RestController
public class Swagger2Controller {

    /**
     * https://www.5axxw.com/wiki/content/k4bgwu
     * @ApiOperation 注解用在方法上，其中value是该方法简短的叙述，notes一般是该方法的详细描述
     * @ApiOperation 注解用于方法，用于表示一个http请求的操作
     * value: 方法的简单描述
     * notes: 方法的详细描述
     * httpMethod: 方法的请求类型
     */
    @ApiOperation(value = "@ApiOperation测试", notes = "此方法用于 @ApiOperation 测试", httpMethod = "GET")
    @GetMapping("/apiOperation")
    public String ApiOperationTest(String str) {
        return str;
    }

    /**
     * @ApiParam 注解的作用: 用于描述参数
     * name:参数名
     * value: 参数的描述信息
     * required:参数是否必须
     *
     * 注意：如果只使用 @ApiParam 注解，那么在生成的API接口文档中参数是body类型
     *
     */
    @ApiOperation(value = "@ApiParam测试", notes = "此方法用于 @ApiOperation 测试")
    @PostMapping("/apiParam")
    public String ApiParamTest(@ApiParam(name = "username", value= "用户名", required = true) String username,
                              @ApiParam(name = "password", value = "密码", required = true) String password) {
        return username + password;
    }

    /**
     * @ApiParam 注解的作用: 用于描述参数
     * name:参数名
     * value: 参数的描述信息
     * required:参数是否必须
     *
     * 注意：如果只使用 @ApiParam 注解，那么在生成的API接口文档中参数是body类型
     * 如果和 @RequestParam 注解一起使用时，那么在生成的API接口文档中参数是query类型
     *
     */
    @ApiOperation(value = "@ApiParam测试2", notes = "此方法用于 @ApiOperation 测试")
    @PostMapping("/apiParam2")
    public String ApiParamTest2(@ApiParam(name = "username", value= "用户名", required = true) @RequestParam String username,
                               @ApiParam(name = "password", value = "密码", required = true) @RequestParam String password) {
        return username + password;
    }

}
